---
title: チャート
icon: '#pro/ChartPie'
---

<MetaData
  lang="ja-JP"
  isPro
  meta={{
    preset: [{
      client: '@univerjs/preset-sheets-advanced',
      locale: '@univerjs/preset-sheets-advanced/locales/en-US',
      style: '@univerjs/preset-sheets-advanced/lib/index.css',
    }],
    plugins: [{
      client: '@univerjs-pro/sheets-chart',
      locale: '@univerjs-pro/sheets-chart/locale/en-US',
    }, {
      client: '@univerjs-pro/sheets-chart-ui',
      facade: '@univerjs-pro/sheets-chart-ui/facade',
      locale: '@univerjs-pro/sheets-chart-ui/locale/en-US',
      style: '@univerjs-pro/sheets-chart-ui/lib/index.css',
    }],
    server: 'No',
  }}
/>

チャートはデータ可視化の重要なツールで、ユーザーがデータを直感的に理解・分析するのに役立ちます。Univer Sheets では、棒グラフ・折れ線グラフ・円グラフなど、さまざまな種類のチャートを提供しています。用途に応じて適切なチャート タイプを選び、データを表示できます。

<PlaygroundFrame lang="ja-JP" slug="sheets/charts" clickToShow />

## プリセットモード

チャート機能は `@univerjs/preset-sheets-advanced` のプリセットに含まれています。

### インストール

<Callout>
  `@univerjs/preset-sheets-advanced` の `UniverSheetsAdvancedPreset` は、実行時に `UniverSheetsDrawingPreset` に依存します。先に `@univerjs/preset-sheets-drawing` をインストールしてください。
</Callout>

```package-install
npm install @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

### 使い方

```typescript
import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced' // [!code ++]
import UniverPresetSheetsAdvancedEnUS from '@univerjs/preset-sheets-advanced/locales/en-US' // [!code ++]
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'
import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing' // [!code ++]
import UniverPresetSheetsDrawingEnUS from '@univerjs/preset-sheets-drawing/locales/en-US' // [!code ++]
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-drawing/lib/index.css' // [!code ++]
import '@univerjs/preset-sheets-advanced/lib/index.css' // [!code ++]

const { univerAPI } = createUniver({
  locale: LocaleType.En_US,
  locales: {
    [LocaleType.En_US]: mergeLocales(
      UniverPresetSheetsCoreEnUS,
      UniverPresetSheetsDrawingEnUS, // [!code ++]
      UniverPresetSheetsAdvancedEnUS, // [!code ++]
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsDrawingPreset(), // [!code ++]
    UniverSheetsAdvancedPreset(), // [!code ++]
  ],
})
```

Univer の商用ライセンスをお持ちの場合は、設定方法について [クライアントでのライセンス](/guides/pro/license#in-preset-mode) を参照してください。

{/* ### プリセットと設定 */}

## プラグインモード

### インストール

```package-install
npm install @univerjs-pro/sheets-chart @univerjs-pro/sheets-chart-ui
```

### 使い方

```typescript
import { UniverSheetsChartPlugin } from '@univerjs-pro/sheets-chart' // [!code ++]
import { UniverSheetsChartUIPlugin } from '@univerjs-pro/sheets-chart-ui' // [!code ++]
import SheetsChartUIEnUS from '@univerjs-pro/sheets-chart-ui/locale/en-US' // [!code ++]
import SheetsChartEnUS from '@univerjs-pro/sheets-chart/locale/en-US' // [!code ++]
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'

import '@univerjs-pro/sheets-chart-ui/facade' // [!code ++]

import '@univerjs-pro/sheets-chart-ui/lib/index.css' // [!code ++]

const univer = new Univer({
  locale: LocaleType.En_US,
  locales: {
    [LocaleType.En_US]: mergeLocales(
      SheetsChartEnUS, // [!code ++]
      SheetsChartUIEnUS, // [!code ++]
    ),
  },
})

univer.registerPlugin(UniverSheetsChartPlugin)
univer.registerPlugin(UniverSheetsChartUIPlugin)
```

Univer の商用ライセンスをお持ちの場合は、設定方法について [クライアントでのライセンス](/guides/pro/license#in-plugin-mode) を参照してください。

## 列挙型

<details>
  <summary>列挙型を表示</summary>
  ```typescript
  export enum ChartAttributeBits {
    Stack = 1 << 30,
    PercentStack = 1 << 29 | ChartAttributeBits.Stack,
    Horizontal = 1 << 28,
  }

  export enum ChartTypeBits {
    None = 0,
    Line = 1 << 1,
    Column = 1 << 2,
    ColumnStacked = ChartTypeBits.Column | ChartAttributeBits.Stack,
    ColumnPercentStacked = ChartTypeBits.Column | ChartAttributeBits.PercentStack,
    Bar = 1 << 2 | ChartAttributeBits.Horizontal,
    BarStacked = ChartTypeBits.Bar | ChartAttributeBits.Stack,
    BarPercentStacked = ChartTypeBits.Bar | ChartAttributeBits.PercentStack,
    Pie = 1 << 3,
    Doughnut = 1 << 8 | ChartTypeBits.Pie,
    Area = 1 << 4,
    AreaStacked = ChartTypeBits.Area | ChartAttributeBits.Stack,
    AreaPercentStacked = ChartTypeBits.Area | ChartAttributeBits.PercentStack,
    Radar = 1 << 5,
    Scatter = 1 << 6,
    Combination = 1 << 7,
  }
  ```
</details>

## Facade API

完全な Facade API の型定義は [FacadeAPI](https://reference.univer.ai/en-US) を参照してください。

Univer Sheets では Facade API を使用して、チャートの作成・設定・管理ができます。Facade API はチャートのためのプログラミング インターフェイスで、チャート機能をより便利に利用できます。

### チャートの挿入

[`FWorksheet.newChart()`](https://reference.univer.ai/en-US/classes/FWorksheet#newchart) メソッドはチャート ビルダーを作成し、`FChartBuilderBase` のインスタンスを返します。メソッド チェーンでチャートの各種プロパティを設定できます。

その後、`build()` を呼び出して `IChartBuilderInfo` オブジェクトを生成し、[`FWorksheet.insertChart(chartBuildInfo: IChartBuilderInfo)`](https://reference.univer.ai/en-US/classes/FWorksheet#insertchart) メソッドでワークシートにチャートを挿入します。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// データ ソース A1:D6 の縦棒グラフを作成
// 開始位置はセル B2 の左上
// チャートの幅は 600、高さは 400
const chartInfo = fWorksheet.newChart()
  .setChartType(univerAPI.Enum.ChartType.Column)
  .addRange('A1:D6')
  .setPosition(1, 1, 0, 0)
  .setWidth(600)
  .setHeight(400)
  .build()
await fWorksheet.insertChart(chartInfo)
```

[`FChartBuilderBase`](https://reference.univer.ai/en-US/classes/FChartBuilderBase) の主なメンバー メソッドは次のとおりです。

| メソッド | 説明 |
| ------ | ----------- |
| addRange | チャートのデータ ソース範囲を指定 |
| setPosition | 行・列のアンカーでチャート位置を設定 |
| setAbsolutePosition | ピクセル値でチャート位置を設定 |
| setChartType | チャートの種類を設定 |
| setWidth | チャートの幅を設定 |
| setHeight | チャートの高さを設定 |
| setOptions | チャート オプションを設定 |
| setTransposeRowsAndColumns | 行と列を入れ替え |
| setTheme | テーマを設定 |
| setXAxisTitle | X 軸のタイトルを設定 |
| setYAxisTitle | Y 軸のタイトルを設定 |
| setRightYAxisTitle | 右 Y 軸のタイトルを設定 |
| setXAxisTextStyle | X 軸タイトルのスタイルを設定 |
| setYAxisTextStyle | Y 軸タイトルのスタイルを設定 |
| setRightYAxisTextStyle | 右 Y 軸タイトルのスタイルを設定 |
| setInvalidValueStrategy | 空セルの表示モードを設定 |
| setAxisPointerStyle | 軸ポインターのスタイルを設定 |
| setALLSeriesStyle | すべての系列のスタイルを設定 |
| setSeriesStyle | 系列インデックスで系列スタイルを設定 |
| build | 挿入/更新用のビルダー情報を生成 |

Univer はさまざまなチャート設定をサポートしており、`setOptions` メソッドで設定できます。設定項目は `IChartBuildOptions` インターフェイスで定義されています。

<details>
  <summary>設定を表示</summary>
  ```typescript
  export interface IChartBuildOptions {
  /**
   * @property {string} [title] チャートのタイトル。
   */
    title?: {
      /**
       * @property {string} [titlePosition] チャート タイトルの位置。
       */
      position?: TitlePositionEnum
    } & IChartTextStyle
    /**
     * @property {string} [legend] チャートの凡例。
     */
    legend?: {
      /**
       * @property {string} [legendPosition] 凡例の位置。利用可能な値: 'top', 'bottom', 'left', 'right', 'hide'。
       */
      position?: LegendPositionEnum
      /**
       * @property {number} [fontSize] 凡例のフォント サイズ。
       */
      fontSize?: number
      /**
       * @property {string} [color] 凡例の文字色。
       */
      color?: string
      /**
       * @property {string} [bold] 凡例のフォント スタイル。
       */
      bold?: boolean
      /**
       * @property {string} [italic] 凡例のフォント ウェイト。
       */
      italic?: boolean
      /**
       * @property {SelectModeEnum} [selectMode] 凡例の選択モード。利用可能な値: 'single', 'multiple', 'close'。
       */
      selectMode?: SelectModeEnum
    }
    /**
     * @property {string} [xAxisTitle] チャートの X 軸タイトル。
     * @example
     * ```typescript
     * chartBuilder.setOptions('xAxisTitle.content', 'xAxis Title text')
     * .setOptions('xAxisTitle.font', 1)
     * .setOptions('xAxisTitle.fontSize', 12)
     * .setOptions('xAxisTitle.fontColor', '#ff0000')
     * .build();
     * ```
     */
    xAxisTitle?: IChartTextStyle
    /**
     * @property {string} [rightYAxisTitle] チャートの Y 軸タイトル。
     */
    yAxisTitle?: IChartTextStyle
    /**
     * @property {string} [rightYAxisTitle] チャートの右 Y 軸タイトル。
     */
    rightYAxisTitle?: IChartTextStyle
    xAxis?: IAxisOptions
    yAxis?: IAxisOptions
    yRightAxis?: IAxisOptions
    axisPointer?: {
      /**
       * @property {string} [indicatorLineType] 軸ポインターの線の種類。
       */
      indicatorLineType?: string
      /**
       * @property {ChartBorderDashType} [indicatorLineColor] 軸ポインターの線の色。可能な値: 'solid', 'dotted', 'dashed'。
       */
      indicatorLineColor?: ChartBorderDashType
      /**
       * @property {string} [indicatorLabelColor] 軸ポインターのラベル背景色。
       */
      indicatorLabelColor?: string
      /**
       * @property {string} [indicatorLabelTextColor] 軸ポインターのラベル文字色。
       */
      indicatorLabelTextColor?: string
    }
    allSeriesStyle?: IAllSeriesStyle
    seriesStyleMap?: {
      [id: string]: ISeriesStyle
    }
    /**
     * @property {string} [area] 折れ線/面グラフのエリア設定。
     */
    area?: {
      lineStyle: AreaLineStyle
    }
    /**
     * @property {string} [backgroundColor] チャートの背景色。
     */
    backgroundColor?: string
    /**
     * @property {string} [borderColor] チャートの枠線色。
     */
    borderColor?: string
    /**
     * @property {boolean} [gradientFill] グラデーション塗りつぶしを使用するか。折れ線グラフでは無効。
     */
    gradientFill?: boolean
    /**
     * @property {string} [theme] チャートのテーマ。
     */
    theme?: string
    /**
     * @property {InvalidValueType} [invalidValueType] 空セルの表示モード。
     */
    invalidValueType?: InvalidValueType
  }
  ```
</details>

設定は setOptions メソッドで行います。以下の 2 通りの指定方法があります。
  - `setOptions(optionPath, optionVal)`: 例 `setOptions('legend.color', '#ff0000')`
  - `setOptions('', IChartBuildOptions)`: 例 `setOptions('', { legend: { color: '#ff0000', bold: true } })`

<details>
  <summary>例: 折れ線グラフを作成</summary>
  ```typescript
  const fWorkbook = univerAPI.getActiveWorkbook()
  const fWorksheet = fWorkbook.getActiveSheet()

  // 折れ線グラフを作成
  const chartInfo = fWorksheet.newChart()
    // 折れ線グラフとして指定
    .asLineChart()
    // データ ソース A1:D6 を設定
    .addRange('A1:D6')
    // 開始位置をセル B2 の左上に設定
    .setPosition(1, 1, 0, 0)
    // 指示線のスタイルを設定
    .setAxisPointerStyle({
      indicatorLabelColor: '#ff0000',
      indicatorLineType: univerAPI.Enum.ChartBorderDashType.Solid,
      indicatorLineColor: '#00ff00',
      indicatorLabelTextColor: '#0000ff',
    })
  // データ点のサイズを 10 に設定
    .setDataPointSize(10)
    // データ点の形状を円に設定
    .setDataPointShape(univerAPI.Enum.LinePointShape.CIRCLE)
    // ビルダー情報を生成
    .build()
  const fChart = await fWorksheet.insertChart(chartInfo)

  // 3 秒後にチャートを更新
  setTimeout(() => {
    if (fChart) {
      // 最初の系列データを取得
      const first = fChart.getSeriesData()[0]
      // 最初の系列の色を赤に設定
      const newChartInfo = fWorksheet.newChart(fChart)
        .setSeriesStyle(first.index, {
          color: '#ff0000',
        })
        .build()
      // チャートを更新
      fSheet.updateChart(newChartInfo)
    }
  }, 3000)
  ```
</details>

Univer は特定の種類のチャートを作成するための次のビルダーを提供します。`fWorkSheet.newChart().asLineChart()` などで作成できます。これらは `FChartBuilderBase` を継承し、固有の設定を持ちます。

```typescript
const lineChartBuilder = fWorkSheet.newChart().asLineChart()
const pieChartBuilder = fWorkSheet.newChart().asPieChart()
const radarChartBuilder = fWorkSheet.newChart().asRadarChart()

// あるいは次の方法でチャート ビルダーを作成できます
const chartBuilder = fWorkSheet.newChart()
  .setChartType(univerAPI.Enum.ChartType.Column)
```

- [LineChartBuilder](https://reference.univer.ai/en-US/classes/LineChartBuilder)

| メソッド | 説明 |
| ------ | ----------- |
| setLineStyle | 線のスタイルを設定。'line' は直線、'smooth' は滑らかな線、'step' は階段状の線 |
| setDataPointShape | データ点の形状を設定。対応形状は LinePointShape を参照 |
| setDataPointColor | データ点の色を設定 |
| setDataPointSize | データ点のサイズを設定 |
| build | チャート挿入/更新用のビルダー情報を生成 |

- [PieChartBuilder](https://reference.univer.ai/en-US/classes/PieChartBuilder)

| メソッド | 説明 |
| ------ | ----------- |
| setDoughnutHole | ドーナツの穴のサイズを設定。範囲は 0〜1 |
| setBorderColor | 円グラフのセクターの色を設定 |
| setHasPaddingAngle | セクターに隙間（分離）を持たせるか設定 |
| setIsHalfPie | 半円グラフにするか設定 |
| setRosePie | ばらグラフにするか設定 |
| setShowLabelLine | ラベル ラインを表示 |
| build | チャート挿入/更新用のビルダー情報を生成 |

- [RadarChartBuilder](https://reference.univer.ai/en-US/classes/RadarChartBuilder)

| メソッド | 説明 |
| ------ | ----------- |
| setShape | レーダー チャートのデフォルト形状を設定。現在の対応値: 'polygon'（多角形）、'circle'（円） |
| setFill | レーダー チャートを塗りつぶすか |
| build | チャート挿入/更新用のビルダー情報を生成 |

### チャートの取得

[`FWorksheet.getCharts()`](https://reference.univer.ai/en-US/classes/FWorksheet#getcharts) メソッドは、現在のワークシートにあるすべてのチャートを取得し、`FChart` オブジェクトの配列を返します。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// アクティブ シート上のすべてのチャートを取得
const charts = fWorksheet.getCharts()
```

[`FChart`](https://reference.univer.ai/en-US/classes/FChart) の主なメンバー メソッドは次のとおりです。

| メソッド | 説明 |
| --- | --- |
| getRange | チャートのデータ ソース範囲を取得 |
| getSeriesData | 系列データを取得 |
| getCategoryData | 分類データを取得 |
| updateRange | チャートのデータ ソース範囲を更新 |

### チャートの更新

[`FWorksheet.updateChart(chartBuildInfo: IChartBuilderInfo)`](https://reference.univer.ai/en-US/classes/FWorksheet#updatechart) メソッドはチャートを更新します。`IChartBuilderInfo` オブジェクトを渡してチャートの設定を更新します。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// データ ソース A1:D6 の縦棒グラフを作成
// 開始位置はセル B2 の左上
const chartInfo = fWorksheet.newChart()
  .setChartType(univerAPI.Enum.ChartType.Column)
  .addRange('A1:D6')
  .setPosition(1, 1, 0, 0)
  .build()
await fWorksheet.insertChart(chartInfo)

// アクティブ シート上のすべてのチャートを取得
const charts = fWorksheet.getCharts()

// 3 秒後に最初のチャートを更新
setTimeout(() => {
  const newChartInfo = fWorksheet.newChart(charts[0])
    .asLineChart()
    .setOptions('legend.position', univerAPI.Enum.LegendPositionEnum.Right)
    .build()
  fWorksheet.updateChart(newChartInfo)
}, 3000)
```

### チャートの削除

[`FWorksheet.removeChart(chart: FChart)`](https://reference.univer.ai/en-US/classes/FWorksheet#removechart) メソッドはチャートを削除します。`FChart` オブジェクトを渡して指定のチャートを削除します。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// データ ソース A1:D6 の縦棒グラフを作成
// 開始位置はセル B2 の左上
const chartInfo = fWorksheet.newChart()
  .setChartType(univerAPI.Enum.ChartType.Column)
  .addRange('A1:D6')
  .setPosition(1, 1, 0, 0)
  .build()
await fWorksheet.insertChart(chartInfo)

// アクティブ シート上のすべてのチャートを取得
const charts = fWorksheet.getCharts()

// 3 秒後に最初のチャートを削除
setTimeout(async () => {
  await fWorksheet.removeChart(charts[0])
  fWorksheet.getCharts()
}, 3000)
```

### チャート テーマ

[`FChartBuilderBase.registerChartTheme(themeName: string, theme: IEchartTheme)`](https://reference.univer.ai/en-US/classes/FWorksheet#registercharttheme) メソッドはチャート テーマを登録します。テーマ名とテーマ オブジェクトを渡してカスタム テーマを登録します。

Univer のチャートは ECharts ライブラリをベースに実装されています。そのため、ECharts の[テーマ ビルダー ツール](https://echarts.apache.org/en/theme-builder.html)でカスタム テーマを作成できます。
このサイトでテーマを作成し、設定ファイルとしてダウンロードしてください。以下の API を使ってカスタム テーマを適用できます。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// テーマを登録
const theme = { // あなたのテーマ オブジェクト
  version: 1,
  themeName: 'myTheme',
  theme: {
    // ... 例示のため一部コードを省略
    color: [
      '#893448',
      '#d95850',
      '#eb8146',
      '#ffb248',
      '#f2d643',
      '#ebdba4',
    ],
    // ... 例示のため一部コードを省略
    visualMapColor: [
      '#893448',
      '#d95850',
      '#eb8146',
      '#ffb248',
      '#f2d643',
      'rgb(247,238,173)',
    ],
    // ... 例示のため一部コードを省略
    axes: [],
    // ... 例示のため一部コードを省略
  },
}
fWorksheet.registerChartTheme('myTheme', theme)

// チャートにカスタム テーマを適用
const chartInfo = fWorksheet.newChart()
  .asLineChart()
  .addRange('A1:D6')
  .setPosition(1, 1, 0, 0)
  .setTheme('myTheme')
  .build()
await fWorksheet.insertChart(chartInfo)
```
